home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / tasks.zip / TASKS.DOC < prev    next >
Text File  |  1990-08-01  |  13KB  |  279 lines
  1.  
  2.                   A Turbo Pascal Task Scheduler
  3.  
  4.  
  5.  
  6. 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . .  2
  7.  
  8. 2. System Criteria.. . . . . . . . . . . . . . . . . . . . . .  2
  9.  
  10. 3. The Procedure Stack and Procedure Scheduling. . . . . . . .  4
  11.  
  12. 4. Error Messages. . . . . . . . . . . . . . . . . . . . . . .  4
  13.  
  14. 5. The Functions.and Procedures. . . . . . . . . . . . . . . .  4
  15.  
  16. 1. Introduction
  17.  
  18.      This Turbo Pascal unit allows the programmer to do a crude
  19. form of scheduling within a Turbo Pascal program. This is written
  20. in Turbo Pascal 4.0 and should do alright at 5.0. This unit can be
  21. used however you want, and distributed freely, so long as there is
  22. no charge for it. I also make no claims as to efficiency or bugs
  23. and will not be considered liable for use, misuse or bugs in the
  24. code. So if you build an important application around this and
  25. something goes wrong, don't expect to sue me, or expect that much
  26. help for that matter. If you are writing applications for public
  27. domain or yourself, then contact me through the BIBMUG BBS in
  28. Buffalo, New York and perhaps I'll give you a hand. That's not
  29. meant to be nasty, I just don't want to be beholden to anyone over
  30. this little bit of code.
  31.      First off, what does it do. This Unit allows you to schedule
  32. procedures do be executed. These are executed according to specific
  33. scheduling criteria established for each procedure and for the
  34. program as a whole. The way this all works is that you 
  35.  
  36.      1. load the procedures with individual scheduling criteria 
  37.                into the procedure stack using add_task.
  38.      2. set the system criteria (optional)
  39.      3. determine the current schedule point
  40.      4. execute the procedures that meet the system and current 
  41.                scheduling criteria using run_tasks.
  42.  
  43. Sounds worse then it is. 
  44.  
  45. 2. System Criteria.
  46.  
  47.      There are four types of system scheduling criteria. These are
  48. define by the enum task_schedule_criteria. This is defined below :
  49.  
  50.      task_schedule_criteria = (
  51.           task_criteria_mod,       {default.}
  52.           task_criteria_equal,
  53.           task_criteria_more,
  54.           task_criteria_less);
  55.  
  56.  
  57.      The first criteria is task_criteria_mod for modulus. In this
  58. a procedure is executed if (current criteria MOD task criteria)
  59. equals 0. This is useful for scheduling procedures to run
  60. periodically. For example, assume proc_1 has a task scheduling
  61. criteria of 10 and it is in code like this :
  62.  
  63.      for i := 1 to 100 do
  64.           run_tasks(i);
  65.  
  66. Then proc_1 will be run 10 times, every 10 cycles of the loop. This
  67. would also be useful in clock driven systems where every X clock
  68. ticks you execute a procedure.
  69.      The next criteria is task_criteria_equal for equals. While the
  70. system is in this mode, procedures whose task schedule number
  71. matches the current schedule number will be executed. For example,
  72. say you have four procedures proc1, proc2 proc3 and proc4 with
  73. scheduling criteria of 1,2,3 and 4 respectively. Now in this loop
  74. :
  75.  
  76.      for i := 1 to 10 do 
  77.           for j := 1 to 4 do
  78.                run_tasks(j);
  79.  
  80. each proc would be run once every cycle for a total of 10 times
  81. each in succession. Another example is this :
  82.  
  83.      for i := 1 to 10 do begin
  84.           if odd(i) 
  85.                then j := 1
  86.                else j := 2;
  87.           run_tasks(j);
  88.           end;
  89.  
  90. where proc1 and proc2 alternate being executed, each running 5
  91. times.
  92.      The last two criteria task_criteria_more and
  93. task_criteria_less are used to set threshold conditions. Basically
  94. when these are set a procedure is executed every time the current
  95. scheduling criteria is greater then or less then the task's
  96. scheduling criteria. In the next example assume the system
  97. scheduling criteria is task_criteria_less and there is a procedure
  98. called fix_stuff in the stack whose task schedule criteria is 5
  99. (make five fixes):
  100.  
  101.      fixes := 1;
  102.      while true do begin   {go until doomsday}
  103.           do_something;
  104.           run_tasks(fixes);
  105.           if fixed then  fixes := fixes + 1; 
  106.           end;
  107.  
  108. As you can see the procedure fix_stuff will be run until five (5)
  109. fixes have been made (whatever that means). Under optimal
  110. conditions one would assume that means five times. Now if you
  111. expand this to include a proc called bigfixes with a criteria of 10
  112. then you'd get 5 fixes with 10 bigger fixes. The task_criteria_more
  113. option works the same way in the opposite direction. So in the
  114. above example, fix_stuff would not be executed until five fixes
  115. were detected and bigfixes until 10 fixes were detected. This is
  116. also useful for running a program that is clock driven but
  117. aperiodic. One could set it so a program only executed after so
  118. many clock ticks had already transpired.
  119. 3. The Procedure Stack and Procedure Scheduling.
  120.  
  121.      Procedures are entered on the procedure stack using the
  122. procedure add_tasks. The address of the procedure to be run and the
  123. scheduling criteria ( a longint number) are passed to it and a task
  124. number is returned. The function itself returns an error code. A
  125. code of task_ok means it was successfully added to the stack.
  126. Programs that meet the current and system criteria are run in the
  127. order they appear on the stack. Thus the stack only contains
  128. pointers to the procedures to be run and their scheduling criteria
  129. and doesn't take up much space in memory. There is a limit of 100
  130. procedures that can be placed on the stack. Attempting to add more
  131. would result in an error of task_full from add_task. The task
  132. number is used for later reference. The number of tasks is a
  133. constant task_limit that is currently set to 100.
  134.      All procedures placed on the stack must be of the same form.
  135. That is procedure <procedure name>(schedule : longint); . Thus the
  136. current scheduling criteria is the only information passed to the
  137. procedure, that is the scheduling criteria passed to run_tasks. Any
  138. deviation will cause a problem. Also any procedure that is to be
  139. placed on the stack must be compiled with the {$F+} compiler option
  140. (force far calls). This allows the program to search for the
  141. procedure outside the units' code segment. This is important. If
  142. the F parameter isn't on, then the program will lock up and will
  143. freeze up you PC.
  144.  
  145. 4. Error Messages
  146.  
  147.      A variety of error messages are available. They are constants
  148. that return the following
  149.      
  150.      task_ok             =    0;
  151.      task_full           =    1;
  152.      task_empty          =    2;
  153.      task_illegal        =    3;
  154.      task_none           =    4;
  155.  
  156. The status task_ok shows that everything is alright. task_full is
  157. returned by add_tasks to indicate that the stack is empty. task
  158. empty is returned by run_tasks to show that there are no tasks to
  159. run. task_illegal is issued in response to an illegal task number
  160. being used (if the number is < 1 or greater the task_limit) and
  161. task_none is used as a result of attempting to perform an operation
  162. on a task that hasn't been loaded into the stack such as
  163. delete_task or change_schedule.
  164.  
  165. 5. The Functions.and Procedures.
  166.      
  167.      These are the functions and procedures that make up the tasks
  168. unit.
  169.  
  170. function add_task(schedule : longint; member : pointer;
  171.                       task_number : byte) : byte;
  172.      Add_task places a procedure on the stack and sets up its
  173. scheduling. It returns a task number used for reference later and
  174. an error code (as part of the function call). the scheduling
  175. criteria is a longint number and the reference to the procedure is
  176. made by passing the address of the procedure to add_tasks.
  177. Add_tasks returns either task_ok or task_full if the stack is full.
  178. For example :
  179.      error := add_tasks(10, @proc1, task_num);
  180.      where proc 1 is defined as procedure proc1(schedule :longint);
  181.      if error = task_full
  182.           then writeln('Stack filled up');
  183.  
  184. The task number is used to refer to it later.
  185.  
  186. function add_task_number(task_number : byte;schedule : longint;
  187.                                member : pointer) : byte;
  188.  
  189.      Add_task_number places a procedure on the stack in the same
  190. way that add_task does, but in a specific place. This is used to
  191. fill in the "holes" left by deletes. It cannot be used to add a
  192. task to the end of the stack, only add_task does that. The space
  193. for the intended addition must be unoccupied (previously deleted)
  194. and legal. If it is occupied or in any way illegal, including being
  195. the end of the stack a task_illegal message is returned. 
  196.  
  197. function space_left : byte;
  198.  
  199.      This tell you how much stack space is left for add_tasks. This
  200. does not taking into account deleted tasks.
  201.  
  202. function first_space : byte;
  203.  
  204.      This returns the place of the first open space or "hole". If
  205. there are no open spaces then zero (0) is returned. If there are no
  206. deleted spaces then the end of the stack is returned.
  207.  
  208. function delete_task(task_number : longint) : byte;
  209.  
  210.      This deletes a task on the stack. The memory that it occupied
  211. is released, and its space is free for another task. To fill it in
  212. later use add_task_number, not add_task. Add task only adds to the
  213. end of the stack. It returns task_illegal if you attempt to delete
  214. a task that isn't there or is out of range.
  215.  
  216. function change_schedule(task_number : byte; 
  217.                          schedule : longint) : byte;
  218.  
  219.      This function changes the scheduling criteria of the task
  220. task_number. As in the other functions, task_illegal is returned if
  221. a bad task number is passed to it. It replaces the old criteria
  222. with the new one.
  223. procedure set_criteria(task_criteria : task_schedule_criteria);
  224.  
  225.      Set_criteria set the system criteria which is of type
  226. task_schedule_criteria. See System Criteria (chapter 2) for more
  227. information.
  228.  
  229.  
  230. function run_tasks(schedule : longint) : byte;
  231.      
  232.      This function run any procedure on the stack whose individual
  233. criteria meet the current criteria in relation to the system
  234. criteria. For more information on scheduling see above. This
  235. returns task_empty if there are no tasks to run.
  236.  
  237. function run_task_number(task_number : byte) : byte;
  238.  
  239.      This function executes task number <task_number> immediately
  240. regardless of criteria. I'm not sure what this could be used for
  241. but, what the heck. It automatically passes the value zero to your
  242. procedure. 
  243.  
  244.                              Index
  245. "hole" . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
  246. {$F+} compiler option. . . . . . . . . . . . . . . . . . . . . .4
  247. Add_task . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
  248. Add_task_number. . . . . . . . . . . . . . . . . . . . . . . . .5
  249. Aperiodic. . . . . . . . . . . . . . . . . . . . . . . . . . . .3
  250. BIBMUG BBS . . . . . . . . . . . . . . . . . . . . . . . . . . .2
  251. Change_schedule. . . . . . . . . . . . . . . . . . . . . . . . .5
  252. Delete_task. . . . . . . . . . . . . . . . . . . . . . . . . . .5
  253. error messages
  254.      error messages. . . . . . . . . . . . . . . . . . . . . . .4
  255. First_space. . . . . . . . . . . . . . . . . . . . . . . . . . .5
  256. Force far calls. . . . . . . . . . . . . . . . . . . . . . . . .4
  257. Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . .4
  258. Procedure stack. . . . . . . . . . . . . . . . . . . . . . . . .4
  259. Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . .4
  260. Run periodically . . . . . . . . . . . . . . . . . . . . . . . .2
  261. Run_task_number. . . . . . . . . . . . . . . . . . . . . . . . .6
  262. Run_tasks. . . . . . . . . . . . . . . . . . . . . . . . . . 4, 6
  263. Set_criteria . . . . . . . . . . . . . . . . . . . . . . . . . .6
  264. Space_left . . . . . . . . . . . . . . . . . . . . . . . . . . .5
  265. System scheduling criteria . . . . . . . . . . . . . . . . . . .2
  266. Task_criteria_equal. . . . . . . . . . . . . . . . . . . . . . .3
  267. Task_criteria_less . . . . . . . . . . . . . . . . . . . . . . .3
  268. Task_criteria_mod. . . . . . . . . . . . . . . . . . . . . . . .2
  269. Task_criteria_more . . . . . . . . . . . . . . . . . . . . . . .3
  270. Task_empty . . . . . . . . . . . . . . . . . . . . . . . . . . .4
  271. Task_full. . . . . . . . . . . . . . . . . . . . . . . . . . . .4
  272. Task_illegal . . . . . . . . . . . . . . . . . . . . . . . . . .4
  273. Task_limit . . . . . . . . . . . . . . . . . . . . . . . . . . .4
  274. Task_none. . . . . . . . . . . . . . . . . . . . . . . . . . . .4
  275. Task_ok. . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
  276. Task_schedule_criteria . . . . . . . . . . . . . . . . . . . . .2
  277. Threshold conditions . . . . . . . . . . . . . . . . . . . . . .3
  278.  
  279.